refactor(core): move the command descriptor registry into its own workspace package - #2348

Size Report

Startup median (7 runs, lower is better):

Android / Smoke Tests failed on e18aa8f (run 34023633671), and I do not believe it belongs to this PR.

The failing step is the live emulator orientation check in smoke-android-emulator:

step: wait for landscape
command: agent-device wait text landscape 10000 --platform android --serial emulator-5554 ...
error.details: { reason: "wait_capture_stalled", captureStalled: true, readableCaptures: 0, timeoutMs: 10000, waitedMs: 10332 }

readableCaptures: 0 means the wait dispatched and its budget resolved correctly — no readable snapshot capture completed on the emulator inside the window. Nothing in this diff touches the capture path: it is a module move, all twelve sources rename at 92–100% with only import specifiers edited, the descriptor tables are unchanged, and the whole versioned help surface is byte-identical to origin/main (82 sections, same sha256). The wait positionals and timeout policy moved unmodified and their unit coverage passes.

This lane is also independently red on recent main pushes — runs 7795, 7788, 7761 — though it passed on this PR's merge base 27a97ee. No fix for it exists that I could port here.

I have re-run the failed job once (my one allowed re-run). Every other completed check on this head is green: Lint & Format, Typecheck & Package, Integration Tests, Compatibility & Provenance, Bundle Size, Ownership and context budgets, command-docs-gate, CodeQL, and the other Smoke Tests lane. If the re-run fails the same way, that is evidence about the emulator lane, not this diff, and I will say so rather than change the PR to chase it.

Generated by Claude Code

The package extraction and gates are otherwise clean at e18aa8f, and CI is green. One source-checkout regression blocks readiness: the daemon signature walker follows only relative imports. The registry and derive modules were previously in that graph; their new workspace imports are ignored. Editing the moved command policy can therefore reuse a daemon running the old implementation.

This shares the signature-resolution fix needed by #2347. Please make that a shared prerequisite rather than adding a second resolver, and prove a package-owned registry edit changes the source daemon signature. Bundled installations are not affected.

This head now conflicts with main. Resolve that alongside the shared source-signature prerequisite from #2347, then rerun the affected gates.

Fixed in 009887e. You were right, and it was wider than the registry: the walk followed relative specifiers only, so every workspace package — kernel, contracts, capture-kit, selectors — has been outside the source-checkout signature since #1490. This PR moved the registry across that boundary, which is what made it observable.

One resolver, in the file #2347 moves. The fix is inside walkDaemonCodeGraph itself, so whichever of us lands first, the other carries it: if #2347 goes first I rebase onto the walker in @agent-device/host-kit; if this does, the move takes the fix with it. No second resolver anywhere.

Three properties worth review:

• Rooted at the walked checkout, not at the walker. import.meta.resolve would have resolved against this module's own location, so a walk of a sibling checkout would fingerprint this one's packages. Resolution goes through <root>/node_modules/@agent-device/<name>, the link the loader follows, and the symlink is resolved so stamps carry repository-relative labels the cache can re-stat.
• The manifest is in the graph. Its exports map is the resolution, and the cache replays a walk's whole input from statSync — so a manifest that chose a module is stamped beside it, and repointing a subpath moves the edge. Manifests are stamped but never scanned: JSON names no imports, and scanning one would drag in each package's whole published surface instead of what the daemon loads.
• Bundled installs unaffected, as you said: dist/src/internal/daemon.js contains zero @agent-device/ strings, so that arm walks exactly as before.

Proof. src/daemon/__tests__/code-signature.test.ts (new, 5 tests): a fixture checkout with a linked workspace package proves the module edit changes the signature while an unexported sibling does not, that repointing the exports map moves the edge, and that an uninstalled package is recorded in absentPaths. The last test is your case on this repository — the real src/daemon.ts walk stamps packages/command-registry/src/registry.ts, catalog.ts and the manifest. Planted red: all 5 fail against the previous walker, all 5 pass with it.

Cost, measured here: 608 → 1,460 modules; cold walk 35ms → ~80ms; the per-invocation cached path 3.1ms → 7.5ms. The two doc comments quoting "~800 modules / ~30ms" are updated rather than left stale.

pnpm check:affected --run at 009887e: all 12 selected checks green except vitest-related, which fails only on the three chmod 0500 tests that also fail at origin/main in this sandbox (uid 0 ignores the mode). A third commit splits the per-file edge resolution out of the walk — Fallow's complexity gate caught it at 9 cyclomatic / 16 cognitive after the fix, so that is a real gate finding, not a cleanup.

Generated by Claude Code

Merged main at b4ebd77 (merge commit, no rebase — #2339 is stacked here). Head is fc40090.

Signature coverage, verified after the merge. #2347 landed the same fix in packages/host-kit/src/code-signature.ts, so this branch's copy is gone: one resolver, the one on main. The walk from src/daemon.ts now stamps 1,461 modules, 12 of them this package — the eleven imported sources plus packages/command-registry/package.json, the manifest whose exports map chose them. Touching packages/command-registry/src/registry.ts changes the signature (graph:1461:80027f71… → graph:1461:90daac5d…). packages/host-kit/src/code-signature.test.ts gains one test pinning that membership, beside the existing test that pins the walker's own.

Conflict: only src/cli/commands/router-types.ts — #2349's CommandProgressState import beside this branch's catalog specifier; both kept. One fixture string in the relocated CLI-route test also went back to the specifier it illustrates, which the move had rewritten as if it were a real import.

The three review points are recorded in the merge commit body. In short: dropping the two entries from HUB_ENTRY_FILES flips denyPlatformImplementations false → true, since the manifest now publishes them as domain facades — both carry the ADR-0019 no-platform-implementation assertion and pass it, and that strengthening is intended. The 150-vs-154 gap is a filter difference: pnpm depgraph collapses to one edge per file pair and I counted value edges only; all three kinds on the same graph give 174 into 67 root files, the shape the issue's own breakdown uses, and both readings drop by exactly 36. The six root-kept tests each need named root symbols (parity: STRUCTURED_BATCH_COMMAND_NAMES, DAEMON_COMMAND_DESCRIPTORS, canRunReplayScopedAction, DaemonRequest; and so on) — full list in the commit.

Re-measured on the new base: daemon → root src/ value edges 148 → 112, still −36. Versioned CLI help byte-identical to b4ebd77 across 82 sections. pnpm check:affected --run at fc40090: all 12 checks green except the three chmod 0500 tests that also fail on origin/main as uid 0.

Generated by Claude Code

Signature-walk cost, re-measured on this head against pre-#2347 main (835af32), since #2347 shipped without these numbers:

The last row is the one on the hot path: resolveLocalDaemonCodeSignature runs it on every command in a source checkout, and it is now ~4.6 ms dearer because the cache re-stats 1,461 stamps instead of 620. That is the price of the fingerprint being honest — the alternative was the stale-daemon bug — but it is worth knowing, and worth revisiting if source-checkout startup gets attention. Corroborates #2347's own independent 619 → 1,459.

Of this package: 11 imported sources plus packages/command-registry/package.json. owner-files.ts is deliberately absent — nothing in the production graph reaches it, which is the property check:bundle-owner-files exists to keep.

Two doc comments in packages/host-kit/src/code-signature-cache.ts and src/daemon/client/daemon-launch-spec.ts still described the pre-#2347 graph ("~800 modules", "~30ms", "returns in ~1.5ms"). This branch corrects them rather than leaving figures that the workspace-following walk had already invalidated.

Generated by Claude Code